home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / NameRegistry.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  29KB  |  785 lines
  1. /*
  2.      File:        NameRegistry.h
  3.  
  4.      Contains:    NameRegistry Interfaces
  5.  
  6.      Version:    Technology:    System 8
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __NAMEREGISTRY__
  19. #define __NAMEREGISTRY__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24.  
  25. #ifdef __cplusplus
  26. extern "C" {
  27. #endif
  28.  
  29. #if PRAGMA_IMPORT_SUPPORTED
  30. #pragma import on
  31. #endif
  32.  
  33. #if PRAGMA_ALIGN_SUPPORTED
  34. #pragma options align=power
  35. /* the following contents can only be used by compilers that support PowerPC struct alignment */
  36.  
  37. #if FOR_SYSTEM7_AND_SYSTEM8_PREEMPTIVE
  38. /*
  39.  These definitions apply to both the System7 and System8 interfaces
  40.  RegEntryRef:    The Global Entry Reference
  41. */
  42. struct RegEntryRef {
  43.     UInt32                             contents[4];
  44. };
  45. typedef struct RegEntryRef RegEntryRef;
  46.  
  47.  
  48. enum {
  49.     kRegPathNameSeparator        = ':'                            /* 0x3A */
  50. };
  51.  
  52.  
  53. enum {
  54.     kRegMaxPropertyNameLength    = 31                            /* Max length of Property Name (terminator not included) */
  55. };
  56.  
  57. typedef char RegPropertyNameBuf[32];
  58. #endif
  59. #if FOR_SYSTEM8_PREEMPTIVE
  60. /*
  61. ------------------------------------------------------------------------------------
  62. Name Registry Interface for System 8
  63. ------------------------------------------------------------------------------------
  64. */
  65. /*
  66. ------------------------------------------------------------------------------------
  67.  Foundation Types
  68. ------------------------------------------------------------------------------------
  69. */
  70. /* Entry Name Definitions (Entry Names are C-Strings)*/
  71.  
  72. enum {
  73.     kRegMaxEntryNameLength        = 47                            /* Max length of a C-String Entry Name (terminator not included) */
  74. };
  75.  
  76. /* length of RegEntryNameBuf = kRegMaxEntryNameLength +1*/
  77. typedef char RegEntryNameBuf[48];
  78. /* Create Entry Options*/
  79. typedef OptionBits RegCreateEntryOptions;
  80. /* use "kNilOptions" for no options*/
  81.  
  82. enum {
  83.     kRegCreateResidentEntry        = 0x00000001                    /* make entry resident */
  84. };
  85.  
  86. /* Delete Entry Options*/
  87. typedef OptionBits RegDeleteEntryOptions;
  88. /* use "kNilOptions" for no options*/
  89.  
  90. enum {
  91.     kRegDeleteEmbeddedEntries    = 0x00000001                    /* delete embedded entries */
  92. };
  93.  
  94. /* Entry Iterator*/
  95. typedef struct OpaqueRegEntryIterator* RegEntryIterator;
  96. /* Entry Iterator Options*/
  97. typedef OptionBits RegEntryIteratorOptions;
  98. /* use "kNilOptions" for no options*/
  99.  
  100. enum {
  101.     kRegIterateEmbeddedEntries    = 0x00000002                    /* iterate embedded entries */
  102. };
  103.  
  104. /*
  105.  Property Instances
  106.  An instance value for a property is assigned by the Name Registry when the
  107.  instance is created.  This value is used to distinguish this instance from any
  108.  other instances of the property.  Instance values are unique and persistent for
  109.  the life of the property. Thus, clients can obtain a reference to a property (name
  110.  and instance value) and use that reference until the property is deleted or the
  111.  system is restarted.  At restart, new instance values are assigned to all
  112.  properties, including any restored persistent properties.
  113. */
  114. typedef UInt32 RegPropertyInstance;
  115.  
  116. enum {
  117.     kRegNilPropertyInstance        = 0x00000000,                    /* nil property instance */
  118.     kRegAnyPropertyInstance        = 0xFFFFFFFF,                    /* any property instance */
  119.     kRegAllPropertyInstances    = 0xFFFFFFFE                    /* all property instances */
  120. };
  121.  
  122. /* Create Property Options*/
  123. typedef OptionBits RegCreatePropertyOptions;
  124. /* use "kNilOptions" for no options*/
  125.  
  126. enum {
  127.     kRegMultiInstanceProperty    = 0x00000001                    /* multiple-instance property */
  128. };
  129.  
  130. /* Property Iterator*/
  131. typedef struct OpaqueRegPropertyIterator* RegPropertyIterator;
  132. /* Transaction Reference*/
  133. typedef struct OpaqueRegTransaction* RegTransaction;
  134. /* Nil Transaction Reference*/
  135. #define kRegNilTransaction    (RegTransaction)0
  136. /*
  137. ------------------------------------------------------------------------------------
  138.  Name Registry Calls
  139. ------------------------------------------------------------------------------------
  140. */
  141. /*
  142. ------------------------------------------------------------------------------------
  143.  EntryRef Handling
  144. ------------------------------------------------------------------------------------
  145. */
  146. /* Compare two EntryRef's for equality. */
  147. extern Boolean RegEntryRefIsEqual(const RegEntryRef *ref1, const RegEntryRef *ref2);
  148.  
  149. /*
  150. ------------------------------------------------------------------------------------
  151.  Adding and Deleting Entries
  152. ------------------------------------------------------------------------------------
  153. */
  154. /*
  155.  Create an Entry
  156.  If (parentEntry) is NULL, the path name is assumed to be an absolute path name
  157.  rooted to the anonymous, unnamed root.  
  158.  Note, RegCreateEntry only creates a single entry, the one at the end of the path.
  159.  Thus, all parent entries along the path to the new entry (ancestors) must already
  160.  exist.
  161. */
  162. extern OSStatus RegCreateEntry(RegTransaction transaction, const RegEntryRef *parentEntry, const char *pathName, RegCreateEntryOptions options, RegEntryRef *newEntry);
  163.  
  164. /*
  165.  Delete an Entry or Subtree
  166.  RegDeleteEntry can be used to delete a single entry or a complete subtree.
  167.  To delete a subtree, set the RegDeleteEmbedded option.
  168.  All properties for deleted entries are also deleted.
  169. */
  170. extern OSStatus RegDeleteEntry(RegTransaction transaction, const RegEntryRef *ref, RegDeleteEntryOptions options);
  171.  
  172. /*
  173. ------------------------------------------------------------------------------------
  174.  LookUp Entry by Name
  175. ------------------------------------------------------------------------------------
  176. */
  177. /*
  178.  Lookup Entry
  179.  Locates an entry given a specified subroot (searchPointRef) and path name.  If the
  180.  searchPointRef pointer is NULL, the path name is assumed to be an absolute path
  181.  name rooted to the root of the Registry.
  182. */
  183. extern OSStatus RegLookupEntry(RegTransaction transaction, const RegEntryRef *searchPointRef, const char *pathName, RegEntryRef *foundEntry);
  184.  
  185. /*
  186. ------------------------------------------------------------------------------------
  187. Get Entry Name and Parent
  188. ------------------------------------------------------------------------------------
  189. */
  190. /*
  191.  Retrieve the name component for the specified entry, and return the EntryRef for
  192.  the parent entry.
  193. */
  194. extern OSStatus RegGetEntryName(RegTransaction transaction, const RegEntryRef *entryRef, RegEntryRef *parentEntry, char *nameComponent);
  195.  
  196. /*
  197. ------------------------------------------------------------------------------------
  198. Get Path Name
  199. ------------------------------------------------------------------------------------
  200. */
  201. /*
  202.  These are utility routines to turn an Entry ID back into a name string.
  203.  Get Entry Path Size
  204.  Note, path size is returned in bytes for C-String paths
  205. */
  206. extern OSStatus RegGetEntryPathSize(RegTransaction transaction, const RegEntryRef *entryRef, ByteCount *pathSize);
  207.  
  208. /* Get Path Name*/
  209. extern OSStatus RegGetEntryPath(RegTransaction transaction, const RegEntryRef *entryRef, char *pathName, ByteCount pathSize);
  210.  
  211. /*
  212. ------------------------------------------------------------------------------------
  213.  Entry Iteration
  214. ------------------------------------------------------------------------------------
  215. */
  216. /*
  217.  An Entry Iterator maintains three variables that are of interest to clients.
  218.  First is an "OutermostScope" which defines the outer boundry of the iteration.
  219.  This is defined by the starting entry and includes that entry plus all of it's
  220.  embedded entries. Second is a "currentScope" which is the entry the iterator is
  221.  currently in. And third is a "currentPosition" which is the last entry returned
  222.  during an iteration.
  223.  Create Entry Iterator
  224.  Create the iterator structure. The outermostScope and currentScope of the iterator
  225.  are set to "startEntry".  If "startEntry" = NULL, the outermostScope and
  226.  currentScope are set to the root entry.  The currentPosition for the iterator is
  227.  set to "nil".
  228.  If propertyName != Null, propertyName, propertyValue, and propertySize are used
  229.  to filter the entries returned during an iteration.  If propertyName == Null, all
  230.  entries are returned.
  231. */
  232. extern OSStatus RegCreateEntryIterator(RegTransaction transaction, const RegEntryRef *startEntry, RegEntryIteratorOptions options, const char *propertyName, const void *propertyValue, ByteCount propertySize, RegEntryIterator *iterator);
  233.  
  234. /* Dispose Entry Iterator*/
  235. extern OSStatus RegDisposeEntryIterator(RegEntryIterator iterator);
  236.  
  237. /*
  238.  Enter Child Entry
  239.  Move an Entry Iterator into the scope of a specified child entry.  The
  240.  currentScope of the iterator is set to the entry specified in "childEntry".  If
  241.  "childEntry" is nil, the currentScope is set to the entry specified by the
  242.  currentPosition of the iterator.
  243.  Note RegEnterEntry cannot be used if the "kRegIterateEmbeddedEntries" option was
  244.  set when the iterator was created. 
  245. */
  246. extern OSStatus RegEnterEntry(RegTransaction transaction, RegEntryIterator iterator, RegEntryRef *childEntry);
  247.  
  248. /*
  249.  Exit to Parent Entry
  250.  Move an Entry Iterator out of the current entry back into the scope of it's parent
  251.  entry. The currentPosition of the iterator is reset to the current entry (the
  252.  previous currentScope), so the next iteration call will continue where it left off.
  253.  This position is returned in parameter "currentPosition".
  254.  Note RegExitEntry cannot be used if the "kRegIterateEmbeddedEntries" option was
  255.  set when the iterator was created. 
  256. */
  257. extern OSStatus RegExitEntry(RegTransaction transaction, RegEntryIterator iterator, RegEntryRef *currentPosition);
  258.  
  259. /*
  260.  Iterate Entries 
  261.  Iterate and return entries contained within the entry defined by the current
  262.  scope of the iterator. If kRegIterateEmbeddedEntries option was specified when the
  263.  iterator was created, all embedded entries will be included in the iteration.  If a
  264.  property selection (name , value, and size) was specified when the iterator was
  265.  created, the only entries having a matching property are returned.  Entries are
  266.  returned one at a time. When OSStatus == nrIterationDone, all entries have been exhausted, and the
  267.  value of nextEntry will be Nil. If changed == true, one or more changes (entry
  268.  create or delete) occured since the last interation call.
  269. */
  270. extern OSStatus RegIterateEntries(RegTransaction transaction, RegEntryIterator iterator, RegEntryRef *nextEntry, Boolean *changed);
  271.  
  272. /*
  273.  Restart Entry Iteration
  274.  Restart an iteration within the current scope.  The iterator is reset such that
  275.  iteration of the contents of the currentScope entry can be restarted. The
  276.  outermostScope and currentScope of the iterator are unchanged. The currentPosition
  277.  for the iterator is set to "nil".
  278. */
  279. extern OSStatus RegRestartEntryIteration(RegEntryIterator iterator);
  280.  
  281. /*
  282. ------------------------------------------------------------------------------------
  283.  Adding and Deleting Properties
  284. ------------------------------------------------------------------------------------
  285. */
  286. /*
  287.  Create Property
  288.  A  single instance property is created by default. To create a multiple-instance
  289.  property set the kRegMultiInstanceProperty option. The next instance of the
  290.  property will be created and the instance value will be returned in
  291.  propertyInstance.
  292. */
  293. extern OSStatus RegCreateProperty(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, const void *propertyValue, ByteCount propertySize, RegCreatePropertyOptions options, RegPropertyInstance *propertyInstance);
  294.  
  295. /*
  296.  Delete Property
  297.  To delete a property the desired property instance(s) must be explicitly
  298.  identified. To delete a single instance property set propertyInstance to
  299.  kRegNilPropertyInstance.  To delete all instances of a multi-instance property, set
  300.  propertyInstance to kRegAllPropertyInstances.  Otherwise, propertyInstance must
  301.  be set to a valid instance value.
  302. */
  303. extern OSStatus RegDeleteProperty(RegTransaction transaction, const RegEntryRef *EntryRef, const char *propertyName, RegPropertyInstance propertyInstance);
  304.  
  305. /*
  306. ------------------------------------------------------------------------------------
  307.  Get/Set Property Values
  308. ------------------------------------------------------------------------------------
  309. */
  310. /*
  311.  Get/Set the value of the specified property for the specified entry.  To get, get
  312.  size, and set property values the desired property instance must be explicitly
  313.  identified.  For single instance properites propertyInstance must  be set to
  314.  kRegNilPropertyInstance.  Otherwise, propertyInstance must be set to a valid
  315.  instance value.
  316.  Get Property size
  317. */
  318. extern OSStatus RegGetPropertySize(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyInstance propertyInstance, ByteCount *propertySize);
  319.  
  320. /* Get Property*/
  321. extern OSStatus RegGetProperty(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyInstance propertyInstance, void *propertyValue, ByteCount *propertySize);
  322.  
  323. /* Set Property*/
  324. extern OSStatus RegSetProperty(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyInstance propertyInstance, const void *propertyValue, ByteCount propertySize);
  325.  
  326. /*
  327. ------------------------------------------------------------------------------------
  328.  Iterating Properties
  329. ------------------------------------------------------------------------------------
  330. */
  331. /*
  332.  Create Property Iterator
  333.  Create the property iterator structure. The target entry is defined by entryRef.
  334.  If a propertyName is specified, only property instances having the specified name
  335.  are returned. If propertyName == nil, all properties are returned.
  336. */
  337. extern OSStatus RegCreatePropertyIterator(RegTransaction transaction, const RegEntryRef *entryRef, const char *propertyName, RegPropertyIterator *iterator);
  338.  
  339. /* Dispose Property Iterator*/
  340. extern OSStatus RegDisposePropertyIterator(RegPropertyIterator iterator);
  341.  
  342. /*
  343.  Iterate Properites
  344.  Iterate and return properties for given entry.  If a propertyName was specified
  345.  when the iterator was created, then only property instances for that name are
  346.  returned. Otherwise, all properties are returned.  The return value in
  347.  propertyInstance will be kRegNilPropertyInstance if the property is single
  348.  instance.  Else it will contain the instance value for the property. If
  349.  changed == true, one or more changes (property creates or deletes) occured since the
  350.  last iterate call.  When OSStatus == nrIterationDone, all properties have been exhausted.
  351. */
  352. extern OSStatus RegIterateProperties(RegTransaction transaction, RegPropertyIterator iterator, char *foundProperty, RegPropertyInstance *propertyInstance, Boolean *changed);
  353.  
  354. /*
  355.  Restart Property Iteration
  356.  Used to re-iterate over a list of properties.  The Property Iterator is reset to
  357.  the beginning of the list of properties for an entry.
  358. */
  359. extern OSStatus RegRestartPropertyIteration(RegPropertyIterator iterator);
  360.  
  361. /*
  362. ------------------------------------------------------------------------------------
  363.  Transaction-control calls
  364. ------------------------------------------------------------------------------------
  365. */
  366. /*
  367.  Begin Transaction
  368.  Marks the beginning of a sequence of Name Registry calls that compose a Registry
  369.  transaction.  An internal data structure for the transaction is created and a
  370.  reference to the transaction is returned in "tranasaction". This reference must be
  371.  used with all subsequence Name Registry calls pertaining to the transaction. The
  372.  transaction reference must be disposed using a RegCommitTransaction or
  373.  RegAbortTranscation call.    
  374. */
  375. extern OSStatus RegBeginTransaction(RegTransaction *transaction);
  376.  
  377. /*
  378.  Commit Transaction
  379.  Commits the changes made to the registry for a sepecified transaction. All changes
  380.  (entry create/delete, property create/delete, and  property value update) made for
  381.  the transaction are atomically integrated into the Registry.  If result ==
  382.  nrTransactionAborted, there was a conflict with changes from some other transaction,
  383.  and this transaction was aborted, i.e., no changes for this transaction were made.
  384.  In this case the transaction should be repeated.
  385.  Note that RegCommitTransaction always disposes the transcation reference
  386.  independant of the outcome of the transaction.  So to repeat a transaaction you
  387.  must start over with a RegBeginTransaction call.
  388. */
  389. extern OSStatus RegCommitTransaction(RegTransaction transaction);
  390.  
  391. /*
  392.  Abort Transaction
  393.  Aborts the changes made to the registry for a sepecified transaction. All changes
  394.  (entry create/delete, property create/delete, and  property value update) made for
  395.  the transaction are disgarded.  
  396.  RegAbortTransaction also disposes of the transcation reference.
  397. */
  398. extern OSStatus RegAbortTransaction(RegTransaction transaction);
  399.  
  400. #endif
  401. #if FOR_SYSTEM7_AND_SYSTEM8_DEPRECATED
  402. /*
  403. ------------------------------------------------------------------------------------
  404.     Name Registry Interface for PowerSurge 1.0.2
  405. ------------------------------------------------------------------------------------
  406. */
  407. /*
  408.  * Name Registry - API for device driver name registration
  409.  *
  410.  * This interface provides access to the namespace used
  411.  * by device drivers.  The data structures and entry points
  412.  * are specialized and simplified for device driver use.
  413. */
  414. /*
  415.  //////////////////////////////////////////////////////////////////////////////
  416. //
  417. // Data Structures
  418. //
  419. */
  420. /*
  421.  //////////////////////////////////////////////////////////////////////////////
  422. // 
  423. // Foundation Types
  424. //
  425. */
  426. /* Value of a property */
  427. typedef void *RegPropertyValue;
  428. /* Length of property value */
  429. typedef UInt32 RegPropertyValueSize;
  430. /*
  431.  //////////////////////////////////////////////////////////////////////////////
  432. // 
  433. // RegEntryID    :    The Global x-Namespace Entry Identifier
  434. //
  435. */
  436. /* RegEntryID:    The Global Entry ID*/
  437. typedef RegEntryRef RegEntryID;
  438. typedef RegEntryID *RegEntryIDPtr;
  439. /*
  440.  //////////////////////////////////////////////////////////////////////////////
  441. //
  442. // Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  443. //
  444. //    * Names are a colon-separated list of name components.  Name components
  445. //      may not themselves contain colons.  
  446. //    * Names are presented as null-terminated ASCII character strings.
  447. //    * Names follow similar parsing rules to Apple file system absolute
  448. //      and relative paths.  However the '::' parent directory syntax is
  449. //      not currently supported.
  450. */
  451. /* Max length of Entry Name */
  452.  
  453. enum {
  454.     kRegCStrMaxEntryNameLength    = 47
  455. };
  456.  
  457. /* Entry Names are single byte ASCII */
  458. typedef char RegCStrEntryName;
  459. typedef char *RegCStrEntryNamePtr;
  460. /* length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1*/
  461. typedef char RegCStrEntryNameBuf[48];
  462. typedef char RegCStrPathName;
  463. typedef UInt32 RegPathNameSize;
  464.  
  465. enum {
  466.     kRegEntryNameTerminator        = 0x00,                            /* '\0' */
  467.     kRegPathNameTerminator        = 0x00                            /* '\0' */
  468. };
  469.  
  470. /*
  471.  //////////////////////////////////////////////////////////////////////////////
  472. //
  473. // Property Name and ID Definitions
  474. //    (Applies to all Properties Regardless of NameSpace)
  475. */
  476.  
  477. enum {
  478.     kRegMaximumPropertyNameLength = 31,                            /* Max length of Property Name */
  479.     kRegPropertyNameTerminator    = 0x00                            /* '\0' */
  480. };
  481.  
  482. typedef char RegPropertyName;
  483. typedef char *RegPropertyNamePtr;
  484. /*
  485.  //////////////////////////////////////////////////////////////////////////////
  486. //
  487. // Iteration Operations
  488. //
  489. //    These specify direction when traversing the name relationships
  490. */
  491. typedef UInt32 RegIterationOp;
  492. typedef RegIterationOp RegEntryIterationOp;
  493.  
  494. enum {
  495.                                                                 /* Absolute locations*/
  496.     kRegIterRoot                = 0x00000002,                    /* "Upward" Relationships    */
  497.     kRegIterParents                = 0x00000003,                    /* include all  parent(s) of entry */
  498.                                                                 /* "Downward" Relationships*/
  499.     kRegIterChildren            = 0x00000004,                    /* include all children */
  500.     kRegIterSubTrees            = 0x00000005,                    /* include all sub trees of entry */
  501.     kRegIterDescendants            = 0x00000005,                    /* include all descendants of entry */
  502.                                                                 /* "Horizontal" Relationships    */
  503.     kRegIterSibling                = 0x00000006,                    /* include all siblings */
  504.                                                                 /* Keep doing the same thing*/
  505.     kRegIterContinue            = 0x00000001
  506. };
  507.  
  508. /*
  509.  //////////////////////////////////////////////////////////////////////////////
  510. //
  511. // Name Entry and Property Modifiers
  512. //
  513.  
  514. //
  515. // Modifiers describe special characteristics of names
  516. // and properties.  Modifiers might be supported for
  517. // some names and not others.
  518. // 
  519. // Device Drivers should not rely on functionality
  520. // specified as a modifier.
  521. */
  522. typedef UInt32 RegModifiers;
  523. typedef RegModifiers RegEntryModifiers;
  524. typedef RegModifiers RegPropertyModifiers;
  525.  
  526. enum {
  527.     kRegNoModifiers                = 0x00000000,                    /* no entry modifiers in place */
  528.     kRegUniversalModifierMask    = 0x0000FFFF,                    /* mods to all entries */
  529.     kRegNameSpaceModifierMask    = 0x00FF0000,                    /* mods to all entries within namespace */
  530.     kRegModifierMask            = 0xFF000000                    /* mods to just this entry */
  531. };
  532.  
  533. /* Universal Property Modifiers */
  534.  
  535. enum {
  536.     kRegPropertyValueIsSavedToNVRAM = 0x00000020,                /* property is non-volatile (saved in NVRAM) */
  537.     kRegPropertyValueIsSavedToDisk = 0x00000040                    /* property is non-volatile (saved on disk) */
  538. };
  539.  
  540. /*
  541.  ///////////////////////
  542. //
  543. // The Registry API
  544. //
  545. /////////////////////// 
  546. */
  547. /*
  548.  ///////////////////////
  549. //
  550. // Entry Management
  551. //
  552. /////////////////////// 
  553. */
  554. /*
  555. -------------------------------
  556.  * EntryID handling
  557. */
  558. /*
  559.  * Initialize an EntryID to a known invalid state
  560.  *   note: invalid != uninitialized
  561. */
  562. extern OSStatus RegistryEntryIDInit(RegEntryID *id);
  563.  
  564. /*
  565.  * Compare EntryID's for equality or if invalid
  566.  *
  567.  * If a NULL value is given for either id1 or id2, the other id 
  568.  * is compared with an invalid ID.  If both are NULL, the id's 
  569.  * are consided equal (result = true). 
  570. */
  571. extern Boolean RegistryEntryIDCompare(const RegEntryID *id1, const RegEntryID *id2);
  572.  
  573. /*
  574.  * Copy an EntryID
  575. */
  576. extern OSStatus RegistryEntryIDCopy(const RegEntryID *src, RegEntryID *dst);
  577.  
  578. /*
  579.  * Free an ID so it can be reused.
  580. */
  581. extern OSStatus RegistryEntryIDDispose(RegEntryID *id);
  582.  
  583. /*
  584. -------------------------------
  585.  * Adding and removing entries
  586.  *
  587.  * If (parentEntry) is NULL, the name is assumed
  588.  * to be a rooted path. It is rooted to an anonymous, unnamed root.
  589. */
  590. extern OSStatus RegistryCStrEntryCreate(const RegEntryID *parentEntry, const RegCStrPathName *name, RegEntryID *newEntry);
  591.  
  592. extern OSStatus RegistryEntryDelete(const RegEntryID *id);
  593.  
  594. /*
  595. ---------------------------
  596.  * Traversing the namespace
  597.  *
  598.  * To support arbitrary namespace implementations in the future,
  599.  * I have hidden the form that the place pointer takes.  The previous
  600.  * interface exposed the place pointer by specifying it as a
  601.  * RegEntryID.
  602.  *
  603.  * I have also removed any notion of returning the entries
  604.  * in a particular order, because an implementation might
  605.  * return the names in semi-random order.  Many name service
  606.  * implementations will store the names in a hashed lookup
  607.  * table.
  608.  *
  609.  * Writing code to traverse some set of names consists of
  610.  * a call to begin the iteration, the iteration loop, and
  611.  * a call to end the iteration.  The begin call initializes
  612.  * the iteration cookie data structure.  The call to end the 
  613.  * iteration should be called even in the case of error so 
  614.  * that allocated data structures can be freed.
  615.  *
  616.  *    Create(...)
  617.  *    do {
  618.  *        Iterate(...);
  619.  *    } while (!done);
  620.  *    Dispose(...);
  621.  *
  622.  * This is the basic code structure for callers of the iteration
  623.  * interface.
  624. */
  625. typedef struct OpaqueRegEntryIter* RegEntryIter;
  626. /*
  627.  * create/dispose the iterator structure
  628.  *   defaults to root with relationship = kRegIterDescendants
  629. */
  630. extern OSStatus RegistryEntryIterateCreate(RegEntryIter *cookie);
  631.  
  632. extern OSStatus RegistryEntryIterateDispose(RegEntryIter *cookie);
  633.  
  634. /*
  635.  * set Entry Iterator to specified entry
  636. */
  637. extern OSStatus RegistryEntryIterateSet(RegEntryIter *cookie, const RegEntryID *startEntryID);
  638.  
  639. /*
  640.  * Return each value of the iteration
  641.  *
  642.  * return entries related to the current entry
  643.  * with the specified relationship
  644. */
  645. extern OSStatus RegistryEntryIterate(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done);
  646.  
  647. /*
  648.  * return entries with the specified property
  649.  *
  650.  * A NULL RegPropertyValue pointer will return an
  651.  * entry with the property containing any value.
  652. */
  653. extern OSStatus RegistryEntrySearch(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize);
  654.  
  655. /*
  656. --------------------------------
  657.  * Find a name in the namespace
  658.  *
  659.  * This is the fast lookup mechanism.
  660.  * NOTE:  A reverse lookup mechanism
  661.  *      has not been provided because
  662.  *        some name services may not
  663.  *        provide a fast, general reverse
  664.  *        lookup.
  665. */
  666. extern OSStatus RegistryCStrEntryLookup(const RegEntryID *searchPointID, const RegCStrPathName *pathName, RegEntryID *foundEntry);
  667.  
  668. /*
  669. ---------------------------------------------
  670.  * Convert an entry to a rooted name string
  671.  *
  672.  * A utility routine to turn an Entry ID
  673.  * back into a name string.
  674. */
  675. extern OSStatus RegistryEntryToPathSize(const RegEntryID *entryID, RegPathNameSize *pathSize);
  676.  
  677. extern OSStatus RegistryCStrEntryToPath(const RegEntryID *entryID, RegCStrPathName *pathName, RegPathNameSize pathSize);
  678.  
  679. /*
  680.  * Parse a path name.
  681.  *
  682.  * Retrieve the last component of the path, and
  683.  * return a spec for the parent.
  684. */
  685. extern OSStatus RegistryCStrEntryToName(const RegEntryID *entryID, RegEntryID *parentEntry, RegCStrEntryName *nameComponent, Boolean *done);
  686.  
  687. /*
  688.  //////////////////////////////////////////////////////
  689. //
  690. // Property Management
  691. //
  692. ////////////////////////////////////////////////////// 
  693. */
  694. /*
  695. -------------------------------
  696.  * Adding and removing properties
  697. */
  698. extern OSStatus RegistryPropertyCreate(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize);
  699.  
  700. extern OSStatus RegistryPropertyDelete(const RegEntryID *entryID, const RegPropertyName *propertyName);
  701.  
  702. /*
  703. ---------------------------
  704.  * Traversing the Properties of a name
  705.  *
  706. */
  707. typedef struct OpaqueRegPropertyIter* RegPropertyIter;
  708. extern OSStatus RegistryPropertyIterateCreate(const RegEntryID *entry, RegPropertyIter *cookie);
  709.  
  710. extern OSStatus RegistryPropertyIterateDispose(RegPropertyIter *cookie);
  711.  
  712. extern OSStatus RegistryPropertyIterate(RegPropertyIter *cookie, RegPropertyName *foundProperty, Boolean *done);
  713.  
  714. /*
  715.  * Get the value of the specified property for the specified entry.
  716.  *
  717. */
  718. extern OSStatus RegistryPropertyGetSize(const RegEntryID *entryID, const RegPropertyName *propertyName, RegPropertyValueSize *propertySize);
  719.  
  720. /*
  721.  * (*propertySize) is the maximum size of the value returned in the buffer
  722.  * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  723.  * value returned.
  724. */
  725. extern OSStatus RegistryPropertyGet(const RegEntryID *entryID, const RegPropertyName *propertyName, void *propertyValue, RegPropertyValueSize *propertySize);
  726.  
  727. extern OSStatus RegistryPropertySet(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize);
  728.  
  729. /*
  730.  //////////////////////////////////////////////////////
  731. //
  732. // Modibute (err, I mean Modifier) Management
  733. //
  734. ////////////////////////////////////////////////////// 
  735. */
  736. /*
  737.  * Modifiers describe special characteristics of names
  738.  * and properties.  Modifiers might be supported for
  739.  * some names and not others.
  740.  * 
  741.  * Device Drivers should not rely on functionality
  742.  * specified as a modifier.  These interfaces
  743.  * are for use in writing Experts.
  744. */
  745. /*
  746.  * Get and Set operators for entry modifiers
  747. */
  748. extern OSStatus RegistryEntryGetMod(const RegEntryID *entry, RegEntryModifiers *modifiers);
  749.  
  750. extern OSStatus RegistryEntrySetMod(const RegEntryID *entry, RegEntryModifiers modifiers);
  751.  
  752. /*
  753.  * Get and Set operators for property modifiers
  754. */
  755. extern OSStatus RegistryPropertyGetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers *modifiers);
  756.  
  757. extern OSStatus RegistryPropertySetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers modifiers);
  758.  
  759. /*
  760.  * Iterator operator for entry modifier search
  761. */
  762. extern OSStatus RegistryEntryMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegEntryModifiers matchingModifiers);
  763.  
  764. /*
  765.  * Iterator operator for entries with matching 
  766.  * property modifiers
  767. */
  768. extern OSStatus RegistryEntryPropertyMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegPropertyModifiers matchingModifiers);
  769.  
  770. #endif
  771.  
  772. #pragma options align=reset
  773. #endif /* PRAGMA_ALIGN_SUPPORTED */
  774.  
  775. #if PRAGMA_IMPORT_SUPPORTED
  776. #pragma import off
  777. #endif
  778.  
  779. #ifdef __cplusplus
  780. }
  781. #endif
  782.  
  783. #endif /* __NAMEREGISTRY__ */
  784.  
  785.